home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3c / ns_lookup.z / ns_lookup
Encoding:
Text File  |  2001-04-17  |  7.8 KB  |  133 lines
  1.  
  2.  
  3.  
  4. NNNNSSSS____LLLLOOOOOOOOKKKKUUUUPPPP((((3333CCCC))))                                                    NNNNSSSS____LLLLOOOOOOOOKKKKUUUUPPPP((((3333CCCC))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ns_lookup, ns_list, ns_close - lookup interface to name service daemon
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<nnnnssss____aaaappppiiii....hhhh>>>>
  13.  
  14.      iiiinnnntttt nnnnssss____llllooooooookkkkuuuupppp((((nnnnssss____mmmmaaaapppp____tttt ****mmmmaaaapppp,,,, cccchhhhaaaarrrr ****ddddoooommmmaaaaiiiinnnn,,,, cccchhhhaaaarrrr ****ttttaaaabbbblllleeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****kkkkeeeeyyyy,,,, cccchhhhaaaarrrr ****lllliiiibbbbrrrraaaarrrryyyy,,,, cccchhhhaaaarrrr ****bbbbuuuuffff,,,, ssssiiiizzzzeeee____tttt lllleeeennnn))));;;;
  15.  
  16.      FFFFIIIILLLLEEEE ****nnnnssss____lllliiiisssstttt((((nnnnssss____mmmmaaaapppp____tttt ****mmmmaaaapppp,,,, cccchhhhaaaarrrr ****ddddoooommmmaaaaiiiinnnn,,,, cccchhhhaaaarrrr ****ttttaaaabbbblllleeee,,,, cccchhhhaaaarrrr ****lllliiiibbbbrrrraaaarrrryyyy))));;;;
  17.  
  18.      vvvvooooiiiidddd nnnnssss____cccclllloooosssseeee((((nnnnssss____mmmmaaaapppp____tttt ****mmmmaaaapppp))));;;;
  19.  
  20.      eeeexxxxtttteeeerrrrnnnn iiiinnnntttt ____ggggeeeettttXXXXbbbbyyyyYYYY____nnnnoooo____ssssttttaaaatttt;;;;
  21.  
  22. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  23.      _n_s__l_o_o_k_u_p, _n_s__l_i_s_t and _n_s__c_l_o_s_e are part of the public interface to the
  24.      UNS name service daemon, nsd(1M).  Ordinarily they are called through
  25.      name service library routines such as getpwnam(3C) and gethostbyname(3N).
  26.  
  27.      When _n_s__l_o_o_k_u_p is called with a particular domain, table and key, it
  28.      first will mmap in a global shared cache database corresponding to the
  29.      table name and attempt to look up the key.  The mdbm database cache
  30.      information is stored in the passed map structure.  If the lookup fails
  31.      then the routine will open a file associated with the key, table and
  32.      domain, and parse the data, in a similar way to flat configuration files.
  33.      The file opened is generated on the fly by the cache miss daemon _n_s_d(_1_M).
  34.  
  35.      The daemon will determine the resolve order for the request then call
  36.      routines in shared libraries for each of the protocols supported to
  37.      answer the request.  Once the data is found it is stored in the global
  38.      shared cache database and a file is generated in memory using the format
  39.      of the flat text file.  The value, if found is returned in buf.  Request
  40.      result types can be found in _n_s__a_p_i._h.
  41.  
  42.      The map structure contains state for the cache file.  The structure is
  43.      defined as:
  44.  
  45.      typedef struct {
  46.           time_t         m_version;
  47.           int       m_flags;
  48.           MDBM      *m_map;
  49.           int       m_stayopen;
  50.      } ns_map_t;
  51.  
  52.      The mmmm____vvvveeeerrrrssssiiiioooonnnn field contains a timestamp; any cache record older than
  53.      this will be ignored.  The mmmm____mmmmaaaapppp field contains a pointer to the map file
  54.      state and should be null on first call.  The mmmm____ssssttttaaaayyyyooooppppeeeennnn field is unused
  55.      by ns_lookup. The mmmm____ffffllllaaaaggggssss bit field contains state for ns_lookup and
  56.      should be set to zero on first call, unless the dynamic creation of
  57.      tables is desired.  In this case, the NS_MAP_DYNAMIC bit of the m_flags
  58.      field should be set.  This will cause ns_lookup() or ns_list() to attempt
  59.      to create the table if it does not exist.  The mapping may be removed by
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. NNNNSSSS____LLLLOOOOOOOOKKKKUUUUPPPP((((3333CCCC))))                                                    NNNNSSSS____LLLLOOOOOOOOKKKKUUUUPPPP((((3333CCCC))))
  71.  
  72.  
  73.  
  74.      a call to nnnnssss____cccclllloooosssseeee, see below.
  75.  
  76.      _n_s__l_i_s_t will return a file handle to an NFS mounted file containing a
  77.      list of all entries for a given domain and table.
  78.  
  79.      _n_s__c_l_o_s_e should be called to remove a cache mapping from memory.  The
  80.      nnnnssss____llllooooooookkkkuuuupppp routine will open a cache file and map it into the process
  81.      memory on first use, and it remains available for the life of the
  82.      process.  The nnnnssss____cccclllloooosssseeee routine can be used to recover the virtual memory
  83.      space or force a reopen of the cache.  This must be called before
  84.      releasing the memory for the ns_map_t structure if dynamically allocated.
  85.  
  86.      Each of the name service API routines call stat(2) on the local files and
  87.      ignore anything in the cache older than these files.  Since the stat call
  88.      is quite expensive this may be skipped by setting the global integer
  89.      _getXbyY_no_stat to a non-zero value.
  90.  
  91. DDDDYYYYNNNNAAAAMMMMIIIICCCC TTTTAAAABBBBLLLLEEEESSSS
  92.      Tables that are not listed in nnnnsssssssswwwwiiiittttcccchhhh....ccccoooonnnnffff((((4444)))) may be created by
  93.      associating them with a parent table.  A parent table is one that is
  94.      marked with the ddddyyyynnnnaaaammmmiiiicccc attribute.  Parent tables cannot support key
  95.      lookup, but exist only to contain  and to provide protocol information to
  96.      dynamically created tables.  See nnnnsssssssswwwwiiiittttcccchhhh....ccccoooonnnnffff((((4444)))) for more information.
  97.      To use dynamic tables, the m_flags field of the nsd_map_t passed to
  98.      ns_lookup or ns_list must have the NS_MAP_DYNAMIC bit set and the table
  99.      name must reference both the parent table and the new dynamic table.  The
  100.      format of the dynamic table reference is the name of the parent table
  101.      name followed by a colon followed by the name of the dynamic table name.
  102.      For the parent table aaaauuuuttttoooommmmoooouuuunnnntttt, the reference for the dynamic table
  103.      aaaauuuuttttoooo____hhhhoooommmmeeee would then be """"aaaauuuuttttoooommmmoooouuuunnnntttt::::aaaauuuuttttoooo____hhhhoooommmmeeee"""".
  104.  
  105. FFFFIIIILLLLEEEESSSS
  106.      /usr/include/ns_api.h
  107.  
  108. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  109.      nsd(1M), networks(4), nsswitch.conf(4)
  110.  
  111. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  112.      The ns_lookup routine returns an integer result code which is one of:
  113.      NS_SUCCESS, NS_NOTFOUND, NS_UNAVAIL, NS_TRYAGAIN, NS_BADREQ, NS_FATAL and
  114.      NS_NOPERM. The ns_list routine will return a FILE pointer which is null
  115.      on failure with errno set.
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.